
/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2018原创作者。
 *
 *根据Apache许可证2.0版许可（“许可证”）；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本：
 *
 *https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证进行的分发是在“按原样”的基础上进行的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证和
 *许可证下的限制。
 */

package org.springframework.jndi;

import javax.naming.NamingException;

import org.springframework.beans.factory.InitializingBean;
import org.springframework.lang.Nullable;
import org.springframework.util.Assert;
import org.springframework.util.StringUtils;

/**
 * Convenient superclass for JNDI-based service locators,
 * providing configurable lookup of a specific JNDI resource.
 *
 * <p>Exposes a {@link #setJndiName "jndiName"} property. This may or may not
 * include the "java:comp/env/" prefix expected by Jakarta EE applications when
 * accessing a locally mapped (Environmental Naming Context) resource. If it
 * doesn't, the "java:comp/env/" prefix will be prepended if the "resourceRef"
 * property is true (the default is <strong>false</strong>) and no other scheme
 * (e.g. "java:") is given.
 *
 * <p>Subclasses may invoke the {@link #lookup()} method whenever it is appropriate.
 * Some classes might do this on initialization, while others might do it
 * on demand. The latter strategy is more flexible in that it allows for
 * initialization of the locator before the JNDI object is available.
 *
 * @author Juergen Hoeller
 * @since 1.1
 * @see #setJndiName
 * @see #setJndiTemplate
 * @see #setJndiEnvironment
 * @see #setResourceRef
 * @see #lookup()
 */
/**
 *用于基于JNDI的服务定位器的方便的超类，
 *提供特定JNDI资源的可配置查找。
 *
 *<p>公开｛@link#setJndiName“jndiName”｝属性。这可能会也可能不会
 *包括雅加达EE应用程序所需的“java:comp/env/”前缀
 *访问本地映射的（环境命名上下文）资源。如果
 *否则，如果“resourceRef”
 *属性为true（默认值为<strong>false</strong>），没有其他方案
 *（例如“java:”）。
 *
 *<p>子类可以在适当的时候调用{@link#lookup（）}方法。
 *有些类可能在初始化时执行此操作，而其他类则可能执行此操作
 *按需提供。后一种策略更灵活，因为它允许
 *在JNDI对象可用之前初始化定位器。
 *
 *@作者于尔根·霍勒
 *@自1.1起
 *@参见#setJndiName
 *@参见#setJndiTemplate
 *@参见#setJndiEnvironment
 *@参见#setResourceRef
 *@参见#lookup（）
 */
public abstract class JndiObjectLocator extends JndiLocatorSupport implements InitializingBean {

	@Nullable
	private String jndiName;

	@Nullable
	private Class<?> expectedType;


	/**
	 * Specify the JNDI name to look up. If it doesn't begin with "java:comp/env/"
	 * this prefix is added automatically if "resourceRef" is set to "true".
	 * @param jndiName the JNDI name to look up
	 * @see #setResourceRef
	 */
	/**
	 *指定要查找的JNDI名称。如果不是以“java:comp/env/”开头
	 *如果“resourceRef”设置为“true”，则会自动添加此前缀。
	 *@param jndiName要查找的JNDI名称
	 *@参见#setResourceRef
	 */
	public void setJndiName(@Nullable String jndiName) {
		this.jndiName = jndiName;
	}

	/**
	 * Return the JNDI name to look up.
	 */
	/**
	 *返回要查找的JNDI名称。
	 */
	@Nullable
	public String getJndiName() {
		return this.jndiName;
	}

	/**
	 * Specify the type that the located JNDI object is supposed
	 * to be assignable to, if any.
	 */
	/**
	 *指定所定位的JNDI对象应具有的类型
	 *可转让给（如有）。
	 */
	public void setExpectedType(@Nullable Class<?> expectedType) {
		this.expectedType = expectedType;
	}

	/**
	 * Return the type that the located JNDI object is supposed
	 * to be assignable to, if any.
	 */
	/**
	 *返回所定位的JNDI对象的假定类型
	 *可转让给（如有）。
	 */
	@Nullable
	public Class<?> getExpectedType() {
		return this.expectedType;
	}

	@Override
	public void afterPropertiesSet() throws IllegalArgumentException, NamingException {
		if (!StringUtils.hasLength(getJndiName())) {
			throw new IllegalArgumentException("Property 'jndiName' is required");
		}
	}


	/**
	 * Perform the actual JNDI lookup for this locator's target resource.
	 * @return the located target object
	 * @throws NamingException if the JNDI lookup failed or if the
	 * located JNDI object is not assignable to the expected type
	 * @see #setJndiName
	 * @see #setExpectedType
	 * @see #lookup(String, Class)
	 */
	/**
	 *为该定位器的目标资源执行实际的JNDI查找。
	 *@返回定位的目标对象
	 *如果JNDI查找失败，或者如果
	 *定位的JNDI对象不可分配给期望的类型
	 *@参见#setJndiName
	 *@参见#setExpectedType
	 *@see#lookup（字符串，类）
	 */
	protected Object lookup() throws NamingException {
		String jndiName = getJndiName();
		Assert.state(jndiName != null, "No JNDI name specified");
		return lookup(jndiName, getExpectedType());
	}

}
